home *** CD-ROM | disk | FTP | other *** search
/ Workbench Add-On / Workbench Add-On - Volume 1.iso / Dev / TileForth / PORTING < prev    next >
Text File  |  1995-08-25  |  6KB  |  251 lines
  1. THREADED INTERPRETIVE LANGUAGE ENVIRONMENT (TILE) PORTING 
  2.  
  3. RELEASE 2.1
  4.  
  5. August 20, 1990
  6.  
  7. Mikael R.K. Patel
  8. Computer Aided Design Laboratory (CADLAB)
  9. Department of Computer and Information Science
  10. Linkoping University
  11. S-581 83 LINKOPING
  12. SWEDEN
  13. Email: mip@ida.liu.se
  14.  
  15.  
  16. INTRODUCTION
  17.  
  18. This brief document describes some to the sections in the tile forth
  19. kernel which may have to be changed to port the code to other machines.
  20. Any changes made should be made in a "#ifdef" section and reported back to
  21. the author in "diff" format.
  22.  
  23.  
  24. 1. KERNEL DEFINITIONS
  25.  
  26. 1.1    Vocabulary listing parameters (File: kernel.c)
  27.  
  28. The column and line width used by "words" may be altered by changing
  29. the lines:
  30.  
  31. #define COLUMNWIDTH 15
  32. #define LINEWIDTH 75
  33.  
  34.  
  35. 1.2    Set of search vocabularies (File: kernel.c)
  36.  
  37. The set of search vocabularies, "context", is realized as a vector
  38. of vocabulary pointers. The maximum number of vocabularies in the set
  39. is defined by:
  40.  
  41. #define CONTEXTSIZE 64
  42.  
  43. An error will occur it the set is exhausted. This limit is not checked
  44. by the kernel.
  45.  
  46.  
  47. 1.3    Lookup cache (File: kernel.c)
  48.  
  49. The vocabulary entry lookup function in the kernel is supported by a
  50. simple cache. A hash function (see below) is used to map a string into 
  51. the cache and there, if possible, find the entry. The size of the cache
  52. is given by:
  53.  
  54. #define CACHESIZE 256
  55. #define hash(s) ((s[0] + (s[1] << 4)) & (CACHESIZE - 1))
  56.  
  57. The hash function is tailored for the current cache size and thus
  58. special care must be taken when altering these definitions.
  59.  
  60.  
  61. 1.4    Internal structures (File: kernel.c)
  62.  
  63. The "pad" and the "tib" may be changed by altering:
  64.  
  65. #define PADSIZE 84
  66. #define TIBSIZE 256
  67.  
  68.  
  69. 1.5    Word alignment (File: kernel.h)
  70.  
  71. Alignment of threaded code and data structures are performed by the
  72. macro:
  73.  
  74. #define align(p) p = (PTR32) ((INT32) ((PTR8) p + 3) & -4)
  75.  
  76. This macro currently aligns to word (long) boundaries and is used by
  77. "colon" and "create".
  78.  
  79.  
  80. 1.6    Typing system (File: kernel.h)
  81.  
  82. The kernel is written in its own typing system. The typing system may
  83. be extended to allow other data types etc. All data types in the kernel
  84. are written with uppercase words.
  85.  
  86. #define VOID void
  87.  
  88. typedef char*  PTR8;
  89. typedef short* PTR16;
  90. typedef long*  PTR32;
  91.  
  92. typedef VOID (*SUBR)();
  93.  
  94. #define NIL 0
  95.  
  96. typedef long BOOL;
  97.  
  98. #define TRUE  ((BOOL) -1)
  99. #define FALSE ((BOOL)  0)
  100.  
  101. typedef unsigned       NUM;
  102. typedef unsigned char  NUM8;
  103. typedef unsigned short NUM16;
  104. typedef unsigned long  NUM32;
  105.  
  106. typedef int   INT;
  107. typedef char  INT8;
  108. typedef short INT16;
  109. typedef long  INT32;
  110.  
  111. typedef float  FLOAT32;
  112. typedef double FLOAT64;
  113.  
  114. typedef char  CHAR;
  115. typedef char* CSTR;
  116. typedef char* PSTR;
  117.  
  118. typedef union {
  119.     BOOL             BOOL;
  120.     NUM32            NUM32;
  121.     INT32            INT32;
  122.     FLOAT32          FLOAT32;
  123.     CSTR             CSTR;
  124.     PTR8             PTR8;
  125.     PTR16            PTR16;
  126.     PTR32            PTR32;
  127.     SUBR             SUBR;
  128.     QUEUE            QUEUE;
  129.     TASK             TASK;
  130.     ENTRY            ENTRY;
  131.     CODE_ENTRY       CODE_ENTRY;
  132.     VOCABULARY_ENTRY VOCABULARY_ENTRY;
  133. } UNIV, *PTR;
  134.  
  135.  
  136. 1.7    Initialization of the kernel (File: kernel.c)
  137.  
  138. The initialization function for the kernel requires five parameters.
  139. The two first allows the application such as forth.c to extend the
  140. basic forth vocabulary by giving the first and last entry in the 
  141. application vocabulary. The three following parameters specify the
  142. size of the foreground task, the forth interpreter. See the file
  143. forth.c for an example.
  144.  
  145.  
  146. 2.     IO MANAGEMENT
  147.  
  148. 2.1    File and path name size (File: io.c)
  149.  
  150. The maximum length of a file or path name is defined as:
  151.  
  152. #define FILENAMESIZE 128
  153. #define PATHNAMESIZE 128
  154.  
  155. These lengths are not test for currently. An error may occur if
  156. a file or path name is longer than the given sizes.
  157.  
  158.  
  159. 2.2    File buffer stack (File: io.c)
  160.  
  161. The io management package implements a stack of input file buffers to
  162. allow loading of files from within other files etc. The maximum depth
  163. of this stack is defined as:
  164.  
  165. #define INFSTACKSIZE 32
  166.  
  167. The depth should be chosen to the maximum number of open files allowed
  168. by the operating system.
  169.  
  170.  
  171. 2.3    Set of loaded files (File: io.c)
  172.  
  173. The file loading mechanism automatically looks if the file already
  174. has been opened. The set of opened files is maintained as a vector.
  175. The maximum number of loaded files is:
  176.  
  177. #define INFILESSIZE 64
  178.  
  179. The vector contains the fully expanded names of the loaded files.
  180. An error may occur if this limit is exceeded. It is not checked for
  181. currently.
  182.  
  183.  
  184. 2.4    Set of paths (File: io.c)
  185.  
  186. The io packages also maintains an ordered collection of paths which
  187. are used to expand file names with when search for the file. The
  188. maximum size of this collection is defined by:
  189.  
  190. #define PATHSSIZE 32
  191.  
  192. This collection is automatically appended by the environment variables
  193. $PWD, $HOME, and $TILEPATH when the io package is initiated.
  194.  
  195.  
  196. 2.5    White space (File: io.h)
  197.  
  198. The definition of "white" space is defined as:
  199.  
  200. #define ISSPACE(c) ((c) <= ' ')
  201.  
  202. This eliminates space and any control characters. Some application
  203. might want to redefine this. 
  204.  
  205.  
  206. 2.6.    Directory separator character (File: io.h)
  207.  
  208. The directory separator character is defined as:
  209.  
  210. #define DIRSEPCHAR '/'
  211.  
  212. This makes the code more portable to other machines.
  213.  
  214.  
  215. 2.6    Non-blocking read operation (File: io.c)
  216.  
  217. To achieve multi-tasking during input wait the input package function
  218. "io_fillbuf" uses a non-blocking read operation. Some environments
  219. do not support this. This may require re-implementation.
  220.  
  221.  
  222. 3.     ERROR MANAGEMENT
  223.  
  224. 3.1    Signals (File: error.c)
  225.  
  226. Error handing is realized using two basic mechanisms; first signals from
  227. the execution environment and second, user defined exceptions in the kernel
  228. (forth level code).
  229.  
  230. The signal message table and the appropriate operations, "error_restart",
  231. or "error_fatal", may have to be changed to give the right performance.
  232.  
  233. Please see these functions and "error_initiate" where the actual binding
  234. of signals and actions is performed.
  235.  
  236.  
  237. 4.    MEMORY MANAGEMENT
  238.  
  239. 4.1    Memory allocation (File: forth.c)
  240.  
  241. Currently memory for the dictionary, strings, entries, and task blocks
  242. are allocated using "malloc".
  243.  
  244. The size of the dictionary is determined when calling the initialization
  245. function, "memory_initiate", in the memory management package. The current
  246. default size is defined as:
  247.  
  248. #define DICTIONARYSIZE 1024L * 1024L
  249.  
  250. And may be too large for "small" machines. 
  251.